🎇 Sparkler: Visual Delight for R

Sparkler is an R package designed to bring joy, delight, and atmosphere to your Shiny apps, RMarkdown documents, and Quarto presentations.

Sparkler solves this by providing lightweight, high-performance visual engines—Confetti, Fireworks, and Atmospheric Weather—that render as full-screen overlays on top of your Shiny apps and RMarkdown documents.

Why use Sparkler?

  • Gamification: Reward users with confetti when they submit a form or hit a target.
  • Storytelling: Use rain, snow, or meteors to set the mood for your data narrative.
  • Zero-Footprint: The effects use a custom Overlay Architecture (Z-index 9999), meaning they float over your app without breaking your Bootstrap layout or blocking mouse clicks.

📦 Installation

You can install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("CodingTigerTang/sparkler")

🎮 Interactive Demo

Option 1: Try it Online

Click the image below to launch the live demo app.

Launch Live Demo

Option 2: Run Locally

library(sparkler)
sparkler::run_demo()

🖥️ Running in R Console

You don’t need Shiny to see the magic! You can run these functions directly in your R console to test them. They will render inside the RStudio Viewer pane.

# Pop some confetti in the viewer
sparkler::confetti()

# Watch a meteor shower
# Note: In the console, weather renders with a dark background so particles are visible.
sparkler::weather(type = "meteor")

# Snowy day
sparkler::weather(type = "snow")

# Fireworks!
sparkler::fireworks()

💻 How to Use in Shiny

Using Sparkler in Shiny requires a slightly different mental model than standard plots.

The Concept: You place an Output function in your UI, but unlike a plot, it takes up 0 pixels of space. It acts as an invisible “antenna.” When you send data to it from the Server, it triggers the JavaScript engine to paint over the whole screen.

Minimal Shiny Example

library(shiny)
library(sparkler)

ui <- fluidPage(
  titlePanel("Sales Dashboard"),
  
  # 1. The Trigger
  actionButton("btn_success", "Close Deal"),
  
  # 2. The Invisible Antenna (Place this anywhere in UI)
  confettiOutput("celebration_effect")
)

server <- function(input, output) {
  
  # 3. The Logic
  observeEvent(input$btn_success, {
    output$celebration_effect <- renderConfetti({
      # Triggers the effect
      confetti(particle_count = 150, spread = 100) 
    })
  })
}

shinyApp(ui, server)

Available Functions

Function UI Output Usage
confetti() confettiOutput() Best for instant feedback (buttons, success messages).
fireworks() fireworksOutput() Best for major milestones. Runs for a set duration.
weather() weatherOutput() Continuous atmosphere (snow, rain, meteors).

📄 How to Use in RMarkdown / Quarto

Sparkler works automatically in HTML documents. There are two distinct ways to use the Weather effect in reports.

Mode 1: The “Atmospheric Overlay” (Fullscreen)

This makes the rain or snow cover the entire webpage, scrolling with the user. Perfect for immersive reports.


```{=html}
<div class="weather html-widget html-fill-item" id="htmlwidget-c870d7878e0ff8e14c15" style="width:672px;height:480px;"></div>
<script type="application/json" data-for="htmlwidget-c870d7878e0ff8e14c15">{"x":{"type":"snow","density":2,"speed":1,"fullscreen":true},"evals":[],"jsHooks":[]}</script>
```

Mode 2: The “Visual Block” (Inline)

If you leave fullscreen as NULL or FALSE, the weather renders inside a specific box, behaving like a standard plot.

## Storm Analysis
Here is a visualization of the storm intensity:


```{=html}
<div id="htmlwidget-d3b72ed24e502c8e2bd1" style="width:672px;height:300px;" class="weather html-widget"></div>
<script type="application/json" data-for="htmlwidget-d3b72ed24e502c8e2bd1">{"x":{"type":"rain","density":1,"speed":2,"fullscreen":false},"evals":[],"jsHooks":[]}</script>
```

🎛 API Reference & Controls

You can fine-tune the physics of every effect.

1. confetti()

  • particle_count (int): Number of confetti pieces (Default: 100).
  • spread (int): How wide the explosion is in degrees (Default: 70).

2. fireworks()

  • duration (int): How many seconds the show lasts (Default: 5).
  • speed (numeric): Speed multiplier. Higher is faster (Default: 1).

3. weather()

  • type (char): One of "snow", "rain", "meteor", or "none".
  • density (numeric): Multiplier for how many particles appear (Default: 1).
  • speed (numeric): Multiplier for how fast they fall/fly (Default: 1).
  • fullscreen (logical): Force full-page overlay. Auto-detected in Shiny, manual in RMarkdown.

⚖️ Credits & Licenses

This package utilizes the following open-source assets:

JavaScript Libraries

  1. canvas-confetti
  2. fireworks-js

Created with ❤️ using htmlwidgets.